[Swift] VVDocumenter-Xcode で Swift プロジェクトの API ドキュメントを記述する

VVDocumenter-Xcode

VVDocumenter-Xcode は iOS アプリの API ドキュメントを効率的に書くための、一番有名な Xcode プラグインです。「///」と入力するだけで構文を自動入力してくれます。

Swift でも使えないかなぁ？と思って改めて Readme を読んでみたら次のような記述がありました。

Swift Support
Yes, this plugin supports documentation for Swift now. Check this post from @mattt to see how to write the documentation for swift. By using VVDocumenter-Xcode, you can just type /// to make the magic happen.

お！できるようになったそうです。この速さは素晴らしいですね！ということで試してみました。

VVDocumenter-Xcode のインストール

Xcode プラグインのインストールは Alcatraz という Xcode プラグインのパッケージマネージャーを利用するのがスタンダードです。

Alcatraz は次のコマンドでインストールできます。

$ curl -fsSL https://raw.github.com/supermarin/Alcatraz/master/Scripts/install.sh | sh

インストール完了後、Xcode を再起動します。メニューの「Window」を開くと「Package Manager」という項目が新たに追加されているはずです。

「Package Manager」をクリックするとパッケージ管理ウインドウが開きます。検索バーに「VV」と入力すると、もう「VVDocumenter-Xcode」しか表示されないと思います。左側のアイコンをクリックするとインストールされます。

インストールが完了するとアイコンが青色に変わります。もう一度再起動すると VVDocumenter-Xcode が利用できるようになります。

appledoc の記述

VVDocumenter-Xcode を入れてしまえば、appledoc の記述は非常に簡単です。Objective-C のときと同様に、対象のクラスやプロパティ、メソッドなどの前の行で「///」と入力するとひな形が挿入されます。引数や戻り値などもバッチリです。

書き終えたら、Option キーを押しながら対象のコードをクリックしてみてください。正しくドキュメント化できていることが確認できます。

なお、Swift 用の API ドキュメントの書き方は下記にまとめられているので、さらに追記したい場合などはこちらを参照してください。ちなみに VVDocumenter-Xcode 自体、この記事を参考に開発したらしいです。

Swift Documentation | NSHipster

API ドキュメントの出力は…

ここまでできたら、あとはドキュメントの出力!!

…と言いたいところですが、筆者が確認した中では、Swift の API ドキュメントを出力できるツールはありませんでした(2014/09/18現在)。なお、API ドキュメント生成ツールとして有名な appledoc は、次期メジャーバージョン(3.0)で Swift に対応する予定らしいです。期待しています！